<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Introduction: GNOME Data Access 5 manual</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="GNOME Data Access 5 manual">
<link rel="up" href="part_libgda-reports.html" title="Part V. Reports">
<link rel="prev" href="part_libgda-reports.html" title="Part V. Reports">
<link rel="next" href="ch35.html" title="API reference">
<meta name="generator" content="GTK-Doc V1.32 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="part_libgda-reports.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="part_libgda-reports.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="ch35.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="libgda-reports-introduction"></a>Introduction</h2></div></div></div>
<p>
	<span class="application">Libgda</span>'s report feature has been reworked and is only offers it <a class="link" href="GdaReportEngine.html" title="GdaReportEngine">report engine object</a>, 
	a low level general usage engine to generate reports in the XML format. More specifically it converts
	an XML tree containing special tags into another XML tree where all the specific tags have been
	expanded/replaced with database contents. For more information about the special tags taken
	into account, please refer to the <a class="link" href="GdaReportEngine.html" title="GdaReportEngine">GdaReportEngine</a>'s
	documentation.
      </p>
<p>
	Working on any XML file allows the report engine to work with all the existing post-processors which will actually
	generate the final file(s) in HTML, PDF or other; for example:
	</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>SVG can be processed by a web browser or further edited using inkscape for example</p></li>
<li class="listitem"><p>DocBook can then be converted to HTML of PDF 
	      (see <a class="ulink" href="http://wiki.docbook.org/topic/DocBookXsltPublishingModelDiagram" target="_top">this docbook Wiki page</a>)
	  </p></li>
<li class="listitem"><p>RML files (Report Markup Language), see <a class="ulink" href="http://www.reportlab.org/" target="_top">ReportLab</a> or
	      <a class="ulink" href="http://oreports.com" target="_top">OpenReports</a> can be converted to HTML or PDF.
	  </p></li>
<li class="listitem"><p>some other XML dialects can also be used such as 
	      <a class="ulink" href="http://sourceforge.net/projects/rlib/" target="_top">RLib</a>, 
	      <a class="ulink" href="http://www.treshna.com/papyrus/" target="_top">Papyrus</a>, and other.
	  </p></li>
</ul></div>
<p>
      </p>
<p>
	To make it easier to use RML or Docbook XML dialects, <span class="application">Libgda</span> has the 
	<a class="link" href="GdaReportDocbookDocument.html" title="GdaReportDocbookDocument">GdaReportDocbookDocument</a> and 
	<a class="link" href="GdaReportRmlDocument.html" title="GdaReportRmlDocument">GdaReportRmlDocument</a> which both offer high level of
	features when dealing with those XML dialects.
      </p>
<p>
	From a programmer's point of view, the following code example shows how to convert the "report-spec.xml" file
	to a "report.xml" report:
	</p>
<pre class="programlisting">
GdaConnection *cnc;
GdaReportEngine *eng
xmlDocPtr doc;
GError *error = NULL;

cnc = gda_connection_open_from_dsn (...);
eng = gda_report_engine_new_from_file ("report-spec.xml");
gda_report_engine_declare_object (eng, G_OBJECT (cnc), "main_cnc");

doc = gda_report_engine_run_as_doc (eng, &amp;error);
if (!doc) {
    /* ERROR */
}
else {
    xmlSaveFile ("report.xml", doc);
    xmlFreeDoc (doc);
}
g_object_unref (eng);
	</pre>
<p>
	For example the XML "report-spec.xml" file could be:
	</p>
<pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"&gt;
&lt;article&gt;
  &lt;articleinfo&gt;
    &lt;title&gt;Customers report example&lt;/title&gt;
    &lt;abstract&gt;
      &lt;!-- Use the "abstract" parameter which is supposed to be defined using gda_report_engine_declare_object() --&gt;
      &lt;para&gt;&lt;gda_report_param_value param_name="abstract"/&gt;&lt;/para&gt;
    &lt;/abstract&gt;
  &lt;/articleinfo&gt;

  &lt;!-- 
       Start a new section, with the "customers" SELECT query, which is supposed to be defined using 
       gda_report_engine_declare_object() 

       Any &lt;gda_report_iter&gt; node will repeat its contents as many times as there are rows in the
       data model returned by the "customers" SELECT query.
    --&gt;
  &lt;gda_report_section query_name="customers" cnc_name="main_cnc"&gt;
    &lt;sect1&gt;
      &lt;!-- Will be replaced by: &lt;title&gt;List of customers (5)&lt;/title&gt; if there are 5 rows for example --&gt;
      &lt;title&gt;List of customers (&lt;gda_report_param_value param_name="customers|?nrows"/&gt;)&lt;/title&gt;

      &lt;!-- List all the customer's names --&gt;
      &lt;ul&gt;
	&lt;gda_report_iter&gt;
	  &lt;li&gt;&lt;gda_report_param_value param_name="customers|@name"/&gt;&lt;/li&gt;
	&lt;/gda_report_iter&gt;
      &lt;/ul&gt;
    &lt;/sect1&gt;
  &lt;/gda_report_section&gt;
&lt;/article&gt;</pre>
<p>
	For a more detailed example, have a look at the <code class="filename">samples/Report</code> of <span class="application">Libgda</span>'s
	sources.
	</p>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.32</div>
</body>
</html>